<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en-US">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.9.6"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>AngelScript: Multithreading</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
  $(document).ready(function() { init_search(); });
/* @license-end */
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr id="projectrow">
  <td id="projectlogo"><img alt="Logo" src="aslogo_small.png"/></td>
  <td id="projectalign">
   <div id="projectname">AngelScript
   </div>
  </td>
    <td>        <div id="MSearchBox" class="MSearchBoxInactive">
        <span class="left">
          <span id="MSearchSelect"                onmouseover="return searchBox.OnSearchSelectShow()"                onmouseout="return searchBox.OnSearchSelectHide()">&#160;</span>
          <input type="text" id="MSearchField" value="" placeholder="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)" 
               onblur="searchBox.OnSearchFieldFocus(false)" 
               onkeyup="searchBox.OnSearchFieldChange(event)"/>
          </span><span class="right">
            <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.svg" alt=""/></a>
          </span>
        </div>
</td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.9.6 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
var searchBox = new SearchBox("searchBox", "search/",'.html');
/* @license-end */
</script>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
      <div id="nav-sync" class="sync"></div>
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(document).ready(function(){initNavTree('doc_adv_multithread.html',''); initResizable(); });
/* @license-end */
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<div id="MSearchResults">
<div class="SRPage">
<div id="SRIndex">
<div id="SRResults"></div>
<div class="SRStatus" id="Loading">Loading...</div>
<div class="SRStatus" id="Searching">Searching...</div>
<div class="SRStatus" id="NoMatches">No Matches</div>
</div>
</div>
</div>
</div>

<div><div class="header">
  <div class="headertitle"><div class="title">Multithreading </div></div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>AngelScript supports multithreading, though not yet on all platforms. You can determine if multithreading is supported on your platform by calling the <a class="el" href="group__api__auxiliary__functions.html#gae1c91abaa2ea97bc2b82ba5e07d3db8b">asGetLibraryOptions</a> function and checking the returned string for <code>"AS_NO_THREADS"</code>. If the identifier is in the returned string then multithreading is not supported.</p>
<p>Even if you don't want or can't use multithreading, you can still write applications that execute <a class="el" href="doc_adv_concurrent.html">multiple scripts simultaneously</a>.</p>
<h1><a class="anchor" id="doc_adv_multithread_1"></a>
Things to think about with a multithreaded environment</h1>
<ul>
<li>If you plan on creating engines in multiple threads, the application should call <a class="el" href="group__api__multithread__functions.html#gaa5bea65c3f2a224bb1c677515e3bb0e2">asPrepareMultithread</a> before the first engine is created, and <a class="el" href="group__api__multithread__functions.html#ga011355a8978d438cec77b4e1f041cba7">asUnprepareMultithread</a> after the last engine has been released. This is to avoid race conditions when the engine creates the internal shared thread manager. If only one script engine is used, then it is not necessary to do go through these extra steps.</li>
<li>Always call <a class="el" href="group__api__multithread__functions.html#ga51079811680d5217046aad2a2b695dc7">asThreadCleanup</a> before terminating a thread that accesses the script engine. If this is not done, the memory allocated specifically for that thread will be lost until the script engine is freed.</li>
<li>If the application is composed of multiple application modules (dlls) then it may be necessary to share a single thread manager across the modules. Do this by calling <a class="el" href="group__api__multithread__functions.html#ga72f005266d6b5258c1dbe10449c78d24">asGetThreadManager</a> in the main module and then call <a class="el" href="group__api__multithread__functions.html#gaa5bea65c3f2a224bb1c677515e3bb0e2">asPrepareMultithread</a> on the secondary modules with the returned pointer.</li>
<li>Multiple threads may execute scripts in separate contexts. The contexts may execute scripts from the same module, but if the module has global variables you need to make sure the scripts perform proper access control so that they do not get corrupted, if multiple threads try to update them simultaneously.</li>
<li>The engine will only allow one thread to build scripts at any one time, since this is something that changes the internal state of the engine and cannot safely be done in multiple threads simultaneously.</li>
<li>Reference counters for objects that will be referred to by scripts in different threads must be thread safe in order to avoid race conditions as multiple threads attempt to update the same reference counter. The library provides a pair of functions to facilitate the implementation of thread safe reference counters. See <a class="el" href="group__api__multithread__functions.html#gaf0074d581ac2edd06e63e56e4be52c8e">asAtomicInc</a> and <a class="el" href="group__api__multithread__functions.html#ga0565bcb53be170dd85ae27a5b6f2b828">asAtomicDec</a>.</li>
<li>Resources that are shared by script modules such as registered properties and objects must be protected by the application for simultaneous access, as the script engine doesn't do this automatically. A read-write lock is provided by the library that can be used for this. See <a class="el" href="group__api__multithread__functions.html#ga016dbf716a1c761b3f903b92eb8bb580">asAcquireExclusiveLock</a>, <a class="el" href="group__api__multithread__functions.html#ga8a0617637eea3d76e33a52758b2cd49f">asReleaseExclusiveLock</a>, <a class="el" href="group__api__multithread__functions.html#gaa45545a038adcc8c73348cfe9488f32d">asAcquireSharedLock</a>, and <a class="el" href="group__api__multithread__functions.html#ga44f7327c5601e8dbf74768a2f3cc0dc3">asReleaseSharedLock</a>.</li>
<li>If you use <a class="el" href="doc_adv_custom_options.html#doc_adv_custom_options_engine">automatic garbage collection</a> (turned on by default) then you must make sure the behaviours registered for types to <a class="el" href="doc_gc_object.html">support garbage collection</a> must be thread safe as the garbage collector can be invoked from any thread that is executing a script.</li>
<li>Many of the add-ons are not thread safe. Either create your own or make sure you review the add-ons you wish to use to guarantee thread safety.</li>
</ul>
<h1><a class="anchor" id="doc_adv_fibers"></a>
Fibers</h1>
<p>AngelScript can be used with fibers as well. However, as fibers are not real threads you need to be careful if multiple fibers need to execute scripts. AngelScript keeps track of active contexts by pushing and popping the context pointers on a stack. With fibers you can easily corrupt this stack if you do not pay attention to where and when script executions are performed.</p>
<p>Try to avoid switching fibers when a script is executing, instead you should <a class="el" href="classas_i_script_context.html#ad4ac8be3586c46069b5870e40c86544a">suspend</a> the current script execution and only switch to the other fiber when the context's <a class="el" href="classas_i_script_context.html#a8e52894432737acac2e1a422e496bf84">Execute</a> method returns. If you really must switch fibers while executing a script, then make sure the second fiber initiates and concludes its own script execution before switching back to the original fiber. </p>
</div></div><!-- contents -->
</div><!-- PageDoc -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    <li class="footer">Generated on Sun May 21 2023 10:12:40 for AngelScript by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.6 </li>
  </ul>
</div>
</body>
</html>
